Documentation Identifiers

Take our previous example of documentation within a comment block.

/**
 * @doc function
 * @name myModule.moduleSection:thisIsAFunction
 *
 * @description This function rules!
 *
 * This is still part of the description!!!
 */

The documentation identifier in this example would be "@doc".

The word "function" which comes right after "@doc" is the doctype . The doctype in most cases tells Docular what rendering method to use, but don't worry about that right now, we'll get into that more later. Let's focus on the identifier attribute for now.

The documentation identifier signifies the start of a new documentation object. It also tells Docular which documentation plugin should be used to parse, manipulate, and display the documentation.

@doc, The Default Documentation Identifier

The default documentation identifier is "@doc". This triggers the use of the default documentation plugin which allows for basic support to group documentation into modules, and then within modules you can further group into classes and globals. It gives a standard view of functions, methods, return values, and parameters.

If you want more information on the specifics of the default @doc API click here!.

@ngdoc, The AngularJS Documentation Identifier

The "@ngdoc" identifier tells Docular to use the AngularJS plugin to parse, manipulate, and render your documentation. It supports different groupings within modules like services, filters, directives, and types.

All documentatio plugins inherit from the default @doc plugin

This means that the AngularJS documentation plugin inherits everything from the default documentation plugin including the ability to split docs into the classes module section.

A sample of what an AngularJS doc would look like using "@ngdoc" identifier would be:

/**
 * @ngdoc service
 * @name myModule.service:myService
 * @description This is the best service ever!!
 *
 * ## No Really it's sweet!
 */

The basis of the @doc plugin along with the additions of the @ngdoc plugin gives the final logic to parse, maniuplate, and display documentation just the way it is done on the AngulerJS documentation site.

If you want more info on the AngularJS @ngdoc API click here!.

Other Documentation Plugins?

Well, there aren't any yet, but if you are feeling frisky, you can certainly make your own. The documentation for creating a documentation plugin is here. (not done yet)

As new plugins become available they will have their own documentation identifier that must take the form "@doc-somename". So suppose I wanted to create my own plugin to parse, manipulate, and display documentation for PHP. The plugin could specify that it's documentation identifier would be "@doc-php". Then all documentation would be scanned and if the documentation section had an identifier of "@doc-php" it would use the API that results from the new plugin that inherited from the default "@doc" api.